<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<link rel="shortcut icon" type="image/x-icon" href="favicon.ico"/>
<title>DynamoRIO API: Symbol Access Library</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">DynamoRIO API
   </div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.1.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('page_drsyms.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Symbol Access Library </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>The <code>drsyms</code> DynamoRIO Extension provides symbol information. Currently drsyms supports reading symbol information from Windows PDB files or Linux ELF, Mac Mach-O, or Windows PECOFF files with DWARF2 line information.</p>
<ul>
<li><a class="el" href="page_drsyms.html#sec_drsyms_setup">Setup</a></li>
<li><a class="el" href="page_drsyms.html#sec_drsyms_paths">Search Paths</a></li>
<li><a class="el" href="page_drsyms.html#sec_drsyms_exports">Exported Functions</a></li>
<li><a class="el" href="page_drsyms.html#sec_drsyms_api">API</a></li>
<li><a class="el" href="page_drsyms.html#sec_drsyms_mem">Memory Usage</a></li>
<li><a class="el" href="page_drsyms.html#sec_drsyms_modbase">Module Bases</a></li>
</ul>
<h1><a class="anchor" id="sec_drsyms_setup"></a>
Setup</h1>
<p>To use <code>drsyms</code> with your client simply include this line in your client's <code>CMakeLists.txt</code> file:</p>
<div class="fragment"><div class="line"> use_DynamoRIO_extension(clientname drsyms) </div>
</div><!-- fragment --><p>That will automatically set up the include path and library dependence.</p>
<p>The <code>drsyms</code> library on Windows relies on the <code>dbghelp.dll</code> library from Microsoft. A copy of the <code>dbghelp.dll</code> library is included. You can also download the Debugging Tools for Windows package from <a href="http://www.microsoft.com/whdc/devtools/debugging/default.mspx">http://www.microsoft.com/whdc/devtools/debugging/default.mspx</a> and place the <code>dbghelp.dll</code> in the same directory as either <code>drsyms.dll</code> or as your client library. Version 6.0 or higher of <code>dbghelp.dll</code> is required, and 6.3 or higher is recommended. Recent versions of Windows do have these versions of <code>dbghelp.dll</code> in their system directories, but be aware that those versions are not redistributable.</p>
<p>The 64-bit version 6.5.0003.7 of <code>dbghelp.dll</code> (the one included with Visual Studio 2005) has a bug that can cause crashes. We recommend avoiding this version.</p>
<p>More recent versions of <code>dbghelp.dll</code> on Windows can use significant amounts of stack space. We have observed usage of 36KB. This is within the default stack size for a DynamoRIO client, but be aware if trying to trim the stack size via the DynamoRIO runtime option <code>-stack_size</code> that anything lower than 36KB is likely to be problematic on Windows.</p>
<p>On Windows, <code>drsyms</code> does support Cygwin and MinGW symbols, and will find file and line information if in DWARF2 format. The <code>stabs</code> format is not supported. Cygwin and MinGW gcc versions prior to 4.3 use <code>stabs</code> by default; pass the <code>-ggdb</code> flag to request DWARF2.</p>
<p>The <code>drsyms</code> library on Linux and Mac uses bundled copies of <code>libelf</code>, <code>libdwarf</code>, and <code>libelftc</code> built from the <a href="http://elftoolchain.sourceforge.net">elftoolchain</a> project and requires no setup.</p>
<h1><a class="anchor" id="sec_drsyms_paths"></a>
Search Paths</h1>
<p>On Linux, <code>drsyms</code> will look in the default debug directories for symbols for a library: a <code>.debug</code> subdirectory of the library's directory or in <code>/usr/lib/debug</code>.</p>
<p>On Mac, for binary <code>foo</code>, <code>drsyms</code> will look in the default <code>dsymutil</code> path of <code>foo.dSYM/Contents/Resources/DWARF/foo</code> for symbols.</p>
<p>On Windows, the <code>_NT_SYMBOL_PATH</code> environment variable is honored by <code>drsyms</code> as a local cache of <code>pdb</code> files. However, <code>drsyms</code> does not support symbol store paths (those that contain <code>srv</code>) when used inside of a DynamoRIO client. Such paths should work fine when used in standalone applications, provided that both <code>symsrv.dll</code> and <code>dbghelp.dll</code> are locatable by the Windows loader.</p>
<h1><a class="anchor" id="sec_drsyms_exports"></a>
Exported Functions</h1>
<p>For clients interested only in locating specific functions exported from a library, it is not necessary to use <code>drsyms</code> as the core DynamoRIO API provides functions for iterating modules and looking up module exports. The following core DynamoRIO API functions are relevant:</p>
<ul>
<li><a class="el" href="dr__tools_8h.html#a8da7923ecc4e020e31442bcc8d9f8d3e">dr_get_proc_address()</a></li>
<li><a class="el" href="dr__tools_8h.html#aace5e8084f523fd25871b31463c7ecda">dr_get_application_name()</a></li>
<li><a class="el" href="dr__events_8h.html#aca6b098123ef80cae05ce767a7dd9d98">dr_register_module_load_event()</a></li>
<li><a class="el" href="dr__tools_8h.html#a4892d089da710e952a23055bd7db38af">dr_lookup_module()</a></li>
<li><a class="el" href="dr__tools_8h.html#addd653edd3322cfb025ef8bdc6ae1060">dr_lookup_module_by_name()</a></li>
<li><a class="el" href="dr__tools_8h.html#a3310b1bfc22da285af72b1a4a9d10945">dr_module_iterator_start()</a></li>
</ul>
<p>These core API routines can be more efficient to use than the <code>drsyms</code> routines, as the latter must locate, load, and parse debug information. However, the core API provides no mechanism for iterating over all exported functions: for that, <code>drsyms</code> must be used. The <code>drsyms</code> API will operate even when no debug information is available, in which case only exported functions will be considered.</p>
<p>On Linux, <code>drsyms</code> searches both <code></code>.dynsym and <code></code>.symtab, while <a class="el" href="dr__tools_8h.html#a8da7923ecc4e020e31442bcc8d9f8d3e">dr_get_proc_address()</a> only searches <code></code>.dynsym. Global symbols in an executable (i.e., a non-library) are only present in <code></code>.symtab by default. If the executable is built with the <code>-rdynamic</code> flag to <code>gcc</code>, its global symbols will be placed in <code></code>.dynsym and thus <a class="el" href="dr__tools_8h.html#a8da7923ecc4e020e31442bcc8d9f8d3e">dr_get_proc_address()</a> will find them. Regardless of how it was built, if it's not stripped, <code>drsyms</code> will find the global symbols.</p>
<h1><a class="anchor" id="sec_drsyms_api"></a>
API</h1>
<p>All functions return a success code of type <a class="el" href="group__drsyms.html#ga78793b36b5a0f529fb746b7ed0072442">drsym_error_t</a>.</p>
<p>Prior to use, <code>drsyms</code> must be initialized by a call to <a class="el" href="group__drsyms.html#ga8f826a91db73acb16acb6649d26a86cd">drsym_init()</a>. The <code>drsyms</code> API will eventually support both sideline and online use, and the parameter to <a class="el" href="group__drsyms.html#ga8f826a91db73acb16acb6649d26a86cd">drsym_init()</a> will specify the symbol server to use for sideline use. Today only online use is supported and <code>NULL</code> should be passed.</p>
<p>Symbol lookup is supported in both directions: from an address to a symbol via <a class="el" href="group__drsyms.html#ga201e8a9bf6746cbfd232bc4e4a243d2b">drsym_lookup_address()</a>, and from a symbol to an address via <a class="el" href="group__drsyms.html#ga2e6f4d91b65fc835c047c8ca23c83d06">drsym_lookup_symbol()</a>. All symbols in a given module can be enumerated via <a class="el" href="group__drsyms.html#ga260c78496165b54b9a97d0a5e1f6f4d8">drsym_enumerate_symbols()</a>, though on Windows using <a class="el" href="group__drsyms.html#gad6eb2e2cee8fba5ee6eb439905b3ecb9">drsym_search_symbols()</a> for a particular match where a non-full search is not required (i.e., the search is only targeting function symbols) is significantly faster and uses less memory than a full enumeration. In fact, <a class="el" href="group__drsyms.html#gad6eb2e2cee8fba5ee6eb439905b3ecb9">drsym_search_symbols()</a> is usually faster than <a class="el" href="group__drsyms.html#ga2e6f4d91b65fc835c047c8ca23c83d06">drsym_lookup_symbol()</a>.</p>
<p>For C++ applications, each routine that handles symbols accepts a <code>flags</code> argument that controls how or whether C++ symbols are demangled or undecorated. Currently there are three modes:</p>
<ul>
<li><code>DRSYM_LEAVE_MANGLED:</code> Matches against or returns the mangled C++ symbol.</li>
<li><code>DRSYM_DEMANGLE:</code> Matches against or returns a "short" demangled C++ symbol. Templates and are collapsed to &lt;&gt; while parameters are omitted entirely without parentheses.</li>
<li><code>DRSYM_DEMANGLE_FULL:</code> Matches against or returns the fully demangled C++ symbol with both template arguments and parameter types.</li>
<li><code>DRSYM_DEMANGLE_PDB_TEMPLATES:</code> Only applies to Windows PDB symbols. Does not affect matches, but returns symbols with parameters omitted without parentheses and templates fully expanded.</li>
<li><code>DRSYM_DEFAULT_FLAGS:</code> This is equivalent to <code>DRSYM_DEMANGLE</code>.</li>
</ul>
<p>On Windows, this functionality is reduced due to the limitations of <code>dbghelp.dll</code>. For all routines except <a class="el" href="group__drsyms.html#gad582a65dc1308335633e0c451035dbe0">drsym_demangle_symbol()</a>, the only flag that the user passes that has any effect is DRSYM_DEMANGLE_PDB_TEMPLATES: all symbols returned or searched either use default demangling or additionally use DRSYM_DEMANGLE_PDB_TEMPLATES if requested.</p>
<p>For an example of usage see the <code>instrcalls</code> sample client distributed with DynamoRIO.</p>
<p>When finished with the library, call <a class="el" href="group__drsyms.html#ga5d70a336713dd08ebe256c2eb964d3ae">drsym_exit()</a>.</p>
<h2><a class="anchor" id="sec_drsyms_mem"></a>
Memory Usage</h2>
<p>When running large applications, loading debug information for all of their modules can occupy a lot of memory, from hundreds of megabytes into the gigabyte range. Use the <a class="el" href="group__drsyms.html#gaf3fc654dfbb2d1e1717ee60229d7ac9f">drsym_free_resources()</a> routine when finished with a module to unload its debug information. Normally, a client will query for symbols in the module load event, and then won't need symbols again until perhaps a callstack walk later on. Thus, we recommend that a client call <a class="el" href="group__drsyms.html#gaf3fc654dfbb2d1e1717ee60229d7ac9f">drsym_free_resources()</a> at the end of its module load event. Due to fragmentation concerns, it is not easy for drsyms itself to perform internal garbage collection at any high frequency.</p>
<h2><a class="anchor" id="sec_drsyms_modbase"></a>
Module Bases</h2>
<p>All <code>drsyms</code> functions operate on relative offsets from a module base, rather than absolute addresses for any given mapping. These are offsets from the in-memory mapping of the module. For Mach-O executables, the module base is considered to be placed after any __PAGEZERO segment. This is especially important for PIE executables on MacOS, where the randomized shift is between the __PAGEZERO segment and the __TEXT segment. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer" style="float:none;text-align:center"><img border=0 src="favicon.png"> &nbsp;  DynamoRIO API version 5.0.0 --- Wed Sep 10 2014 21:36:44 &nbsp; <img border=0 src="favicon.png">
</small></address>
<!--END !GENERATE_TREEVIEW-->
</body>
</html>
